docs(apply): build ids are checked before anything is applied - #186

Summary

Documents forge-cli #803 (open). Under --mode amend-and-build or replace-and-build, fluid apply now checks id and every builds[].id against the build phase's rule, right after the schema check. The check runs before the apply hooks, tofu and any build. A bad id is refused with apply_build_identifier_invalid.

Before this, such an id (1orders, or one longer than 128 characters) passed fluid validate. On the OpenTofu engine the product was provisioned first, and the build runner then refused the id as "Unexpected error".

forge-cli #803 is on main (squash-merged as 87559062, 2026-11-03), so the "on main" wording is now true and this is ready to merge.

• The text was checked against #803 head e7f60572. The final head, 6b3cdadb, only changed an import in the test file, so the documented behaviour and output are unchanged.
• When the release ships, the "On forge-cli main, not yet in a release" markers become "since X.Y.Z".
• A follow-up forge-cli PR will make fluid validate and fluid plan warn about such ids (validate --strict fails on the warning). It should also update the sentence that says they pass 1orders.

Related CLI PR

• CLI PR: fix(apply): refuse an unusable build id before tofu apply forge-cli#803

Areas Updated

• Getting Started
• CLI Reference: docs/cli/apply.md gets a "Build ids" subsection under Contract validation, with the rule, a real output block and what changed, plus a row in "Errors you can hit".
• Provider Docs
• Walkthroughs / Examples
• Contributing / Community Docs
• Other: a bullet in docs/upgrading.md under "On forge-cli main since 0.26.0". It covers what to do (rename the id), and that a renamed id gets a new .fluid/iac/<provider>/<id> workdir and starts its builds without their cursors and watermarks.

Checklist

• I previewed the change locally with npm run docs:dev or built it with npm run docs:build
• I checked links, page titles, and navigation where relevant
• Screenshots or command output are updated if needed

Notes

• Output block: from a real fluid apply run of the #803 branch. It is the full refusal as printed, suggestions included.
• Checks run locally: each was run against the pinned data-product-forge==0.26.0 on Python 3.11, as CI does, and all pass.
  • check_cli_docs.py, its --version-only and --markers-only modes, check_providers.py and gen_contract_reference.py --check.
  • npm run docs:build, then scripts/check-dist-links.mjs: clean over 244 pages. The #build-ids anchor is in the built cli/apply.html.
  • lychee --offline over the two pages: no new errors. The only 3 errors are existing root-relative links at apply.md:660-662, which CI resolves with its staged root dir.